<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
  <meta http-equiv="expires" content="Fri, 26 Dec 2003 19:13:00 +0100" />
  <meta name="language" content="en" />
  <meta name="robots" content="index,follow" />
  <meta name="revisit-after" content="7 days" />
  <meta name="author" content="Dominique Stender, Paul Sullivan" />
  <meta name="date" content="2003-11-26T18:13:00+01:00?" />
  <meta name="description" content="Documentation for the CPAINT AJAX toolkit" />
  <meta name="keywords" content="AJAX, CPAINT, Asynchronous JavaScript and XML, XML, JavaScript, PHP, ASP, .NET, Perl" />
  <title>CPAINT documentation :: developer's guide :: frontend</title>
  <link rel="stylesheet" href="cpaint.css" media="screen" />
  <link rel="stylesheet" href="cpaint.print.css" media="print" />
  <script type="text/javascript" src="js/menu.js"></script>
  <style type="text/css">
<!--
.menu1 {font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 10px;
	text-decoration: none;
	font-weight:  bold;
}
-->
  </style>
</head>
<body>
  <p align="right">
    <br />
    <a href="http://sf.net/projects/cpaint/">
      <img src="gfx/css_logo.gif" alt="" border="0" height="51" width="182" alt=""  />
    </a>
  </p>
  <h1>CPAINT :: Cross-Platform Asynchronous INterface Toolkit</h1>
  <div id="menu">
    <h2>Contents</h2>
    <p>
      <script type="text/javascript">
      <!--
        generate_menu();
      //-->
      </script>
    </p>
    <br /><br /><br />
    <p>
      <img src="gfx/xhtml10.gif" alt="" border="0" height="15" width="80" /><br />
      <img src="gfx/css.gif" alt="" border="0" height="15" width="80" /><br />
      <a href="http://www.monorom.to/" target="_blank"><img src="gfx/monorom.gif" alt="monorom" border="0" height="15" width="80" /></a><br />
    <a rel="license" href="http://creativecommons.org/licenses/by/1.0/" target="_blank"><img src="gfx/cc.gif" alt="Creative Commons License" border="0" height="15" width="80" /></a></p>
    <p><br />
      <a href="http://creativecommons.org/licenses/by/1.0/" target="_blank" class="menu" rel="license">Project Services By <br />
      </a><a href="http://sourceforge.net/" target="_blank" class="menu1"><img src="http://sourceforge.net/sflogo.php?group_id=141041&amp;type=2" width="125" height="37" border="0" alt="SourceForge.net Logo"/></a> </p>
  </div>
  
  <div id="content">
    <h2>Developer's Guide : Frontend </h2>
    <div id="summary">
      <h3>Frontend Guide: Pages</h3>
      <p>
        <a href="usage.frontend.html" class="code">introduction</a><br />
        <a href="usage.frontend.page2.html" class="code">integrating CPAINT</a><br />
        <a href="usage.frontend.page3.html" class="code">working with CPAINT</a><br />
        <a href="usage.frontend.page4.html" class="code">using the proxy</a><br />
        <a href="usage.frontend.page5.html" class="code">non-CPAINT data-sources</a><br />
        <a href="usage.frontend.page6.html" class="code">browser compatibility tests</a><br />
      </p>
    </div>
    <h3>Retrieving Data from Local Sources Not Using CPAINT</h3>
    <p>If you need to retrieve data from a script that is local to your web page, but does not use CPAINT (another AJAX toolkit or Webservices script, for instance), you can simply set <a href="frontend.class.cpaint.set_use_cpaint_api.html" class="code">cpaint.set_use_cpaint_api()</a> to <span class="code">false</span> and use the same calling conventions you would as for the proxy script (you do <strong>NOT</strong> need to set  <a href="frontend.class.cpaint.set_proxy_url.html" class="code">cpaint.set_proxy_url()</a>, as the data will be retrieved directly by the browser). </p>
    <h3>URL Format</h3>
    <p>No matter which method you use to retrieve data from the backend, we understand that sometimes the script isn't always available on the default HTTP port (port 80) or that it may require a username and password to access. <em>It may be possible to utilize other protocols, but we have not tested it and at this time will not support it. But please <a href="support.html">contact</a> us if you feel there is need for improvement.</em> </p>
    <p>CPAINT supports the use of alternative port numbers and HTTP basic authentication. Here is the standard format for URLs that we support. Sections in brackets (&quot;[&quot;, &quot;]&quot;) are not required. </p>
    <blockquote>
      <p class="code">http://[userid:password@]server.domain.tld[:port]/path</p>
    </blockquote>
    <h3>XML and plaintext response types combined</h3>
    <p>
      As a CPAINT use pointed out, there are situations when you might want to create an XML structure via the CPAINT backend <em>but still</em> need to access that response as plaintext (and not as DOM structure). An example for this would be if you're using CPAINT in conjunction with an XML parser XMLJS (<a href="http://xmljs.sourceforge.net/" target="_blank">http://xmljs.sourceforge.net/</a>).
    </p>
    <p>
      To make this possible CPAINT will call your local callback function with two parameters since version 2.0.1.
    </p>
    <blockquote>
      <pre class="code">
        &lt;script src="cpaint2.inc.js" type="text/javascript"&gt;&lt;/script&gt;
        &lt;script type="text/javascript"&gt;
          &lt;!--
          var cp = new cpaint();
          cp.set_response_type('XML');
    
          function trigger() {
            cp.call('xml_backend.asp', 'get_XML', parser);
        
          function parser(DOM_struct, XML_source) {
            /* 
            * do something with either the DOM structure
            * or the plain XML code available through the 
            * second parameter.
            */
          }
          //--&gt;
        &lt;/script&gt;
      </pre>
    </blockquote>
    <p>
      <strong>Note </strong> that in the above example CPAINT is configured to generate a XML response.<br />
      Since CPAINT v2.0.1 the local callback function <span class="code">parser()</span> will be called by CPAINT with two parameters:<br />
    <ol>
        <li>The first parameter will contain the response as defined by <a href="frontend.class.cpaint.set_response_type.html" class="code">cpaint.set_response_type()</a> - in this case a DOM object tree because we have configured CPAINT to use XML.</li>
        <li>The second parameter will <em>always</em> contain the raw plaintext response, regardless of the response type configured. So, for response type TEXT the first parameter will contain the un-escaped text response, while the second parameter will contain the raw response including all escape sequences, e.g. <span class="code">\u0010</span> for line feeds.</li>
    </ol>
    </p>
    <p>
    It is important to realize that the second argument in your local callback function is <em>optional</em>. So if you're upgrading your CPAINT library there is no need to re-write your callbacks.
    </p>
    <p>
    <div id="nav_left">
        &laquo; <a href="usage.frontend.page4.html">back to page 4</a>
    </div>
      <div id="nav_right">
        &raquo; <a href="usage.frontend.page6.html">continue to page 6</a>
      </div>
    </p>
  </div>
</body>
</html>
